package io.github.echarts.model.theme;

import java.util.List;

/**
 * 配色方案接口
 * <p>
 * 定义了图表使用的配色方案，包括主要颜色系列、强调色、背景色等。
 * 配色方案是主题的重要组成部分，影响图表的整体视觉效果。
 * </p>
 */
public interface ColorScheme {
    
    /**
     * 获取颜色方案名称
     * 
     * @return 方案名称
     */
    String getName();
    
    /**
     * 获取主要颜色列表
     * <p>
     * 这些颜色通常用于系列、类目等的配色，是配色方案的主体部分。
     * </p>
     * 
     * @return 颜色列表
     */
    List<String> getColors();
    
    /**
     * 获取指定索引的颜色
     * <p>
     * 如果索引超出颜色列表范围，则循环使用列表中的颜色。
     * </p>
     * 
     * @param index 颜色索引
     * @return 颜色值
     */
    default String getColor(int index) {
        List<String> colors = getColors();
        if (colors == null || colors.isEmpty()) {
            return "#5470c6"; // 默认蓝色
        }
        return colors.get(Math.abs(index) % colors.size());
    }
    
    /**
     * 获取背景颜色
     * 
     * @return 背景颜色
     */
    String getBackgroundColor();
    
    /**
     * 获取文本颜色
     * 
     * @return 文本颜色
     */
    String getTextColor();
    
    /**
     * 获取轴线颜色
     * 
     * @return 轴线颜色
     */
    String getAxisLineColor();
    
    /**
     * 获取分隔线颜色
     * 
     * @return 分隔线颜色
     */
    String getSplitLineColor();
    
    /**
     * 获取强调色
     * <p>
     * 用于突出显示的元素，如高亮、选中状态等。
     * </p>
     * 
     * @return 强调色
     */
    String getEmphasisColor();
    
    /**
     * 获取警告色
     * <p>
     * 用于表示警告信息的颜色。
     * </p>
     * 
     * @return 警告色
     */
    String getWarningColor();
    
    /**
     * 获取成功色
     * <p>
     * 用于表示成功状态的颜色。
     * </p>
     * 
     * @return 成功色
     */
    String getSuccessColor();
    
    /**
     * 获取错误色
     * <p>
     * 用于表示错误状态的颜色。
     * </p>
     * 
     * @return 错误色
     */
    String getErrorColor();
} 